ToolBarOpen is used to open your application’s tool bar beneath the menu bar on your main monitor. Your application can have only one tool bar.
Window specifies the tool bar’s window number (just like an ordinary window). Once the tool bar is opened, it is referenced by this window number. If a window using the same window number is already open, it is closed, then a new tool bar is opened as specified by the parameters in the ToolBarOpen procedure, thereby re-using the window number. The newly opened tool bar is always “active,” and it becomes “current” (action pertaining to graphics, text, buttons, scroll bars, etc. occurs in this window). Tools Plus allows up to 50 windows to be open simultaneously, however, you may choose to reduce this limit when using InitToolsPlus to initialize Tools Plus. If a tool bar is open and you try to open another toolbar using a different window number, ToolBarOpen does nothing.
Height specifies the tool bar’s height. A 1-pixel window frame is drawn just below the tool bar. The tool bar’s height can be up to 70 pixels, but application’s typically have tool bars that seldom exceed 30 pixels.
The tool bar’s procID influences the behavior of other windows in your application. Two constants are available to assist in the implementation of a tool bar, either or both of which can be used to specify a tool bar procID. If you decide not to use either of the available options, specify a procID of 0.
tbShiftWindows Shift all open windows downward by an amount that
is equal to the menu bar’s height to prevent
windows from being obscured by the tool bar.
When the tool bar is closed, the windows are
shifted up by the identical amount.
tbOffsetNewWindows If new windows are opened while the tool bar is
open, offset their co-ordinates downward by an
amount that is equal to the menu bar’s height to
prevent windows from being obscured by the tool
bar. This option lets you use a standard set of
window locations and have them automatically
offset depending on whether the tool bar is open
or not.
Tool bars are typically colored a medium gray on color or gray-scale monitors, so you may want to declare a global variable of type RGBColor (appropriately named ToolBarGray) that has the red, green and blue components set to 52428. When the tool bar is opened or whenever it is refreshed, you can paint its contents with the ToolBarGray if ScreenDepth is greater than or equals 4.
CONST {Tool Bar options: }
tbShiftWindows =$01; {Shift windows down when tool bar opens }
tbOffsetNewWindows=$02; {Offset future windows when they open }
Close an open window, tool bar or floating palette.
pascal void WindowClose (short Window);
procedure WindowClose(Window: INTEGER);
The WindowClose procedure closes a window that was opened by WindowOpen, or a tool bar that was opened with ToolBarOpen. If a standard window is being closed, the window immediately behind the newly closed window (if one exists) becomes active and current.
Window specifies the window number that is closed. If the specified window is not open, WindowClose does nothing.
When a window is closed, it automatically releases the memory that was consumed by its associated buttons (including radio buttons and check boxes), picture buttons, pop-up menus, scroll bars, editing fields, list boxes, and custom controls. If the affected window contains an active editing field, that field is automatically deactivated before the window is closed. The impact to your application is that you must save the field’s edited text (with the SaveFieldString routine) before closing the window. If you want to validate the field’s edited text before saving it, see the GetFieldString routine.
When working with windows that are opened and closed frequently, you can take advantage of the WindowDisplay routine which hides and displays a window. This is particularly useful when used on a tool bar or a floating palette because a hidden window remembers the settings of all the objects on the window (picture buttons, check boxes and radio buttons, editing fields, etc.) as well as the window’s location. When the window is displayed again, it is identical in position and appearance as when it was hidden.
The WindowSize routine is used to change a window’s width and/or height without changing its position on the screen. In most situations, windows that need resizing are best accommodated by the documentProc procID which provides a grow box in the bottom right corner of the window, and optionally a zoom box in the title bar. Some applications, however, need a window that presents an “expanded” view. An example of this the Macintosh’s Alarm Clock desk accessory which expands to let the user change the time, calendar and alarm timer. Your application should change a window’s size only in response to some action taken by the user.
Window specifies the window number that is resized. If the specified window is not open or if it’s hidden, WindowSize does nothing.
Width and Height specify the window’s new dimensions in pixels. These dimensions relate to those specified by the WindowOpen routine, that is, they represent the content region or usable area of the window (the window’s frame, shadow, and title bar are all created outside of these co-ordinates). The tool bar’s width cannot be changed, and its height cannot exceed 70 pixels. All other windows’ new dimensions are automatically adjusted to keep them within the window’s size limits which are set with SetWindowSizeLimits. If you specify zero (0) for either of these dimensions, it specifies that dimensions (height or width) should not be changed (i.e., WindowSize(1, 80, 0, true) changes window 1’s width to 80 pixels and leaves the height unchanged.
Update specifies if the newly exposed area is added to the window’s update region (thereby producing a doRefresh event). If you specify true, the newly exposed area is added to the window’s update region. If you specify false, your application will handle the newly exposed area.
WindowMove repositions a window on the screen without changing its size. Do not use WindowMove in place of having the user move a window to a new location by dragging the title bar. Windows should only be moved in response to a user’s action, such as selecting an “Arrange Windows” menu item that arranges all open windows in a specified manner (grid or tile, for example).
Window specifies the window number that is moved. If the specified window is not open or if it’s hidden, WindowMove does nothing.
HGlobal and vGlobal specify the window’s new location in global co-ordinates. These dimensions relate to the top left corner specified by the WindowOpen routine, that is, they represent the top left corner of the content region or usable area of the window (the window’s frame, shadow, and title bar are all created outside of these co-ordinates). The tool bar cannot be moved.
ProcID specifies optional behavior that can take place while moving the window. The value for this 2-byte integer can be specified by adding a set of constants to obtain the desired result. The options are:
wAnimateMove Show “zoom lines” that move from the window’s
original position to the window’s new position
(see the ZoomLines routine for details).
wOffsetForToolBar Offset the specified vertical co-ordinate
downward by the tool bar’s height (if a tool bar
is open).
CONST {Window moving options: }
wAnimateMove = $01; {Animate with Zoom Lines }
wOffsetForToolBar = $02; {Offset co-ords by tool bar’s height }
From a user’s perspective, a window that is “hidden” by your application is actually being closed. If a standard window is hidden, the standard window behind it is activated. When a window is displayed (unhidden), it appears as though the window was opened, in that it appears at the front of its layer and becomes “active” and “current.” Your application should hide and show windows in response to a user’s action, such as selecting a “Hide Tool Bar” menu item. Tools Plus automatically hides the tool bar and all floating palettes when your application is suspended under MultiFinder or System 7, and displays them when your application is activated.
Window specifies the window number that is hidden or shown. You cannot hide a modal window.
Show indicates if the window is being hidden or displayed. The two constants that can be used for this flag are wShow and wHide.
When working with windows that are opened and closed frequently, you can take advantage of WindowDisplay instead of closing the window and opening it and having to recreate its contents. This is particularly useful when used on a tool bar or a floating palette because a hidden window remembers the settings of all the objects on the window (picture buttons, check boxes and radio buttons, editing fields, etc.) as well as the window’s location. When the window is displayed again, it is identical in position and appearance as when it was hidden.
Before you hide a window, realize that the user thinks the window is being closed (even though it may only be temporary). Don’t leave the window in an “unsettled” state when your are hiding it. Make sure that all editing fields are validated and processed.
When a window is hidden, it does not release any memory consumed by its associated user interface elements such as buttons (including radio buttons and check boxes), picture buttons, pop-up menus, scroll bars, editing fields, list boxes, and custom controls. If a window is being hidden and it contains an active editing field, that field is automatically deactivated before the window is hidden. The impact to your application is that you must save the field’s edited text (with the SaveFieldString routine) before hiding the window. If you want to validate the field’s edited text before saving it, see the GetFieldString routine.
Window specifies the window number that is activated. The specified window is brought forward and becomes “active” and “current.” This window is also considered to be the “work” window. If the window is hidden or not open, ActivateWindow does nothing.
If the tool bar is activated, it simply becomes the current window (because the tool bar is always active). If a floating palette is activated, it is brought to the front of the floating palette layer without deactivating any windows. When a standard window is activated, it is brought to the front of the standard window layer, and the previously active standard window is deactivated
A window will normally be activated only in response to a doChgWindow event that is reported during polling. Another possible use of ActivateWindow is if your application has a “Window” menu that lets the user activate a window from a menu. Don’t mysteriously activate an inactive window.
Make a window the current window without activating it.
pascal void CurrentWindow (short Window);
procedure CurrentWindow(Window: INTEGER);
Subsequent window related operations such as drawing, and creating fields, buttons, scroll bars, etc., will occur in the specified window without making it the “active” window. This routine is used to redirect your application’s actions to a window other than the active one.
Window specifies the window number in which subsequent window related operations will occur. If the specified window is not open, CurrentWindow does nothing.
The CurrentWindowReset procedure resets window operations back to the “active” window making the active window current too. You should get into the habit of leaving the active window current. It makes debugging much simpler.
Reset the “current” window to be the same as the “active” window.
pascal void CurrentWindowReset(void);
procedure CurrentWindowReset;
Subsequent window related operations such as drawing, and creating fields, buttons, scroll bars, etc., will occur in the “active” window. This procedure nullifies the effect of the CurrentWindow procedure making the “active” window current also. If your application uses a tool bar and/or floating palettes, then the work window will become current.
The WindowTitle procedure changes the title for an open window, regardless if it is active or not. You can only see the change on windows that have a title bar (documentProc, noGrowDocProc, rDocProc, paletteProc and ordPaletteProc). You won’t see any change on windows that do not display titles (dBoxProc, plainDBox, altDBoxProc, altPaletteProc, and the tool bar).
Window specifies the window number in which the title is to be changed. The specified window does not have to be the “active” window, however, the window must be opened to display the title. Hidden windows will display the new title once they become visible. If the window is not open, WindowTitle does nothing.
MinHoriz specifies the minimum width (in pixels) the window may attain when being sized.
MinVert specifies the minimum height (in pixels) the window may attain when being sized.
MaxHoriz specifies the maximum width (in pixels) the window may attain when being sized.
MaxVert specifies the maximum height (in pixels) the window may attain when being sized.
SetWindowSizeLimits affects only the current window. If the current window is not a Tools Plus window, SetWindowSizeLimits does nothing. The minimum and maximum limits imposed on a window are automatically adjusted (if necessary) to ensure that the window’s current size does not exceed the adjusted limits. For example, if the minHoriz limit is set to 100 pixels and the window is currently 90 pixels wide (10 pixels smaller than the specified minimum width), minHoriz is adjusted to 90 pixels. The same applies if the maximum limit is exceeded by the window’s current dimensions.
By setting these limits, it is possible to allow a window to be sized horizontally or vertically only.
Set a window’s standard co-ordinates and user co-ordinates that are in effect when the window’s “zoom box” is clicked.
pascal void SetWindowZoom (Rect *userRect, Rect *stdRect);
procedure SetWindowZoom(userRect, stdRect: RECT);
A window containing a zoom box has two different states: [1] the standard state, and [2] the user state. The user can change the window’s size and/or location, thereby defining the user state. When the zoom box is clicked, the window “zooms” back to the standard state (which, by default, is the window’s co-ordinates when it was first opened). Clicking the zoom box again reverts to the user state.
Sometimes it is desirable to have the standard state and/or user state something other than the window’s initial co-ordinates. SetWindowZoom sets either or both of these. The window’s current co-ordinates become the user state. It is good form to call SetWindowZoom immediately after opening a window.
UserRect defines a rectangle in global co-ordinates that determines the window’s user co-ordinates. If the current window is not a Tools Plus window, if the current window has no zoom box, or if an empty rectangle is specified, the user co-ordinates are not set.
StdRect defines a rectangle in global co-ordinates that determines the window’s standard co-ordinates. If the current window is not a Tools Plus window, if the current window has no zoom box, or if an empty rectangle is specified, the standard co-ordinates are not set.
If the tool bar is open and it was created with the tbOffsetNewWindows option, this window’s co-ordinates for userRect and stdRect are shifted downwards by an amount that is equal to the tool bar’s height.
Warning: When you set the user and standard co-ordinates, make sure that
they are such that at least part of the window’s title bar is
visible to allow the window to be dragging back into view
(don’t zoom to an “off-screen” window). Ideally, the zoom box
A window containing a zoom box has two different states: [1] the standard state, and [2] the user state. The user can change the window’s size and/or location, thereby defining the user state. When the zoom box is clicked, the window “zooms” back to the standard state (which, by default, is the window’s co-ordinates when it was first opened). Clicking the zoom box again reverts to the user state.
UserRect defines the window’s user state in the screen’s global co-ordinates.
StdRect defines the window’s standard state in the screen’s global co-ordinates.
If the tool bar is open and it was created with the tbOffsetNewWindows option, this window’s userRect and stdRect are shifted upwards by an amount that is equal to the tool bar’s height (i.e., they are shifted up as though there was no tool bar)..
GetWindowZoom gets the values for the current window. If the current window is not a Tools Plus window, or if the current window has no zoom box, the userRect and stdRect rectangles are undefined. This procedure is useful if you want to save both states as part of the document. When the document is opened, a window could be created using the userRect co-ordinates, and the user and standard state can be set by using the SetWindowZoom procedure.
procedure WindowStatus(Window: INTEGER; var Status: TPWindowStatus);
The WindowStatus procedure returns the status of any Tools Plus window, whether it is open or closed, displayed or hidden.
Window is the window number of a Tools Plus window. Window must be less than or equal to MaxWindows as defined by InitToolsPlus. If it is not, the Status record is initialized to “false” and 0 values. MaxWindows defines the maximum number of Tools Plus windows that may be open at any time.
The Status record contains information about the Tools Plus window indicated by the Window value. The record is defined as such:
struct TPWindowStatus {
short Kind; /*Tool Bar, Palette, or Standard kind */
Boolean Open; /*Is the window open? */
Boolean Visible; /*Is this window visible (not hidden)? */
Boolean Active; /*Is this window active? */
Boolean Front; /*Is this front most Tools Plus window? */
Boolean Current; /*Is this the current window? */
Boolean WorkWindow; /*Is this the work window? */
Boolean EditFieldWindow;/*Does window have app's active field? */
short ActiveField; /*Window's active field number */
Rect StrucRect; /*Window’s structure rect (global) */
Rect ContRect; /*Window’s content rect (global) */
};
typedef struct TPWindowStatus TPWindowStatus;
TPWindowStatus = record { }
Kind: integer; {Tool Bar, Palette, or Standard kind }
Open: boolean; {Is the window open? }
Visible: boolean; {Is this window visible (not hidden)? }
Active: boolean; {Is this window active? }
Front: boolean; {Is this front most Tools Plus window? }
Current: boolean; {Is this the current window? }
WorkWindow: boolean; {Is this the work window? }
EditFieldWindow: boolean;{Does window have app's active field? }
ActiveField: integer; {Window's active field number }
StrucRect: rect; {Window’s structure rect (global) }
ContRect: rect; {Window’s content rect (global) }
end;
Kind indicates the kind of window being referenced. The various kinds of windows are:
wNoKind = 0 Window is not open
wToolBarKind = 1 Tool Bar
wFloatingKind = 2 Floating palette
wStandardKind = 3 Standard window
Open indicates if the referenced window is open.
Visible indicates if the referenced window is visible or not. The term “visible” refers to being programatically unhidden. It does not mean “obscured by other windows or objects.”
Active indicates if the referenced window is active. A Tools Plus window will not be active under any of the following conditions:
• the window is not open
• the referenced window is a standard window, but not the front most
standard window
• the active window is a desk accessory (System 5/6’s Finder only)
Front indicates if the referenced window is the front most window in your application. If your application is not using a tool bar or floating palettes, the front most window is active unless:
• a desk accessory is active
• another application or the Finder is active (under MultiFinder or
System 7)
Current indicates if the referenced window is the current window. If your application does not use a tool bar or floating palettes, current and active are the same unless you used the CurrentWindow procedure to change the current window number.
WorkWindow indicates if the referenced window is the work window. This is the same as active if your application does not use a tool bar or floating palettes.
EditFieldWindow indicates if the referenced window contains your application’s active editing field (see the Editing Fields chapter for details).
ActiveField specifies the active editing field number for the referenced window. For standard windows, this field becomes active when the window is active. For the tool bar and floating palettes, this field is active while the application is active.
StrucRect is the window’s structure rectangle in global co-ordinates. This includes the window’s frame, shadow, and title bar.
ContRect is the window’s content rectangle in global co-ordinates. This is the window’s usable area excluding the window’s frame, shadow, and title bar.
Get the window number of the active window (or work window number if a tool bar and/or floating palettes are used).
pascal short ActiveWindowNumber(void);
function ActiveWindowNumber: INTEGER;
This function returns the window number of the active window. If your application does not have a tool bar or floating palettes, this is the front most window. When a tool bar and/or floating palettes are used, ActiveWindowNumber returns the work window number. A value of zero (0) is returned if any of the following conditions occurs:
• no windows are open
• the active window is a desk accessory
• another application or the Finder is active (under MultiFinder or
System 7)
Also see: CurrentWindowNumber, FirstWindowNumber, FirstStdWindowNumber, FirstPaletteNumber and WorkWindowNumber.
This function returns the window number of the current window. If your application does not have a tool bar or floating palettes, this window is the same as the active window unless you used the CurrentWindow procedure to change the current window. A value of zero (0) is returned if any of the following conditions occurs:
• no windows are open
• the current window is a desk accessory
• another application or the Finder is current (under MultiFinder or
System 7)
Also see: ActiveWindowNumber and FirstWindowNumber.
Get the window number of your application’s front most window.
pascal short FirstWindowNumber(void);
function FirstWindowNumber: INTEGER;
This function is typically used to determined the front most window in order to close it or apply some equally universal operation to that window. If your application does not have a tool bar or floating palettes, this is your application’s front most window. If your application has a tool bar or floating palettes, FirstWindowNumber returns the number of the window that satisfies any of the following conditions (in ascending order of priority):
• the front most modal window (it is a standard window)
• the front most floating palette (if one is open and visible)
• the front most modeless standard window (if one is open and
visible)
FirstWindowNumber always ignores the tool bar.
A value of zero (0) is returned if no windows are open. Note that the front most window in your application will not be the active window under any of the following conditions:
• a desk accessory is active
• another application or the Finder is active (under MultiFinder or
System 7)
Also see: CurrentWindowNumber, FirstWindowNumber, FirstStdWindowNumber, FirstPaletteNumber and WorkWindowNumber.
Get the window number of your application’s tool bar.
pascal short ToolBarNumber(void);
function ToolBarNumber: INTEGER;
This function returns the window number of your application’s tool bar. If your application does not have a tool bar, or if the tool bar has been hidden, ToolBarNumber returns a value of zero (0). You can use this routine in place of a global variable to determine if an event pertains to the tool bar.
Get the window number of your application’s front most floating palette.
pascal short FirstPaletteNumber(void);
function FirstPaletteNumber: INTEGER;
This function returns the window number of your application’s front most visible floating palette. If your application does not have floating palettes, or if they are all hidden, FirstPaletteNumber returns a value of zero (0).
Get the window number of your application’s front most standard window.
pascal short FirstStdWindowNumber(void);
function FirstStdWindowNumber: INTEGER;
This function returns the window number of your application’s front most visible standard window. If your application does not have standard windows, or if they are all hidden, FirstStdWindowNumber returns a value of zero (0). Note that this window may be modal.
